Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / adikit.arc / ADIKIT.DOC < prev next >

Wrap

Text File | 1986-12-01 | 104.9 KB | 2,638 lines

Autodesk, Inc. Autodesk Device Interface/ADI Driver Development Kit Version 2.1 _______ Graphics Displays Digitizers Plotters Printer/Plotters Publication TDADIDOC01.00 December 1, 1986 Product of Autodesk, Inc. This publication is distributed by Autodesk so that independent parties can develop graphics peripheral device drivers independently of Autodesk, Inc. This publication, or parts thereof, as well as associated materials distributed on diskette, and software developed using these materials, i.e. ADI device drivers intended to function with Autodesk, Inc. software products, may be distributed freely without royalty to Autodesk, Inc., subject to the following conditions. Users of the ADI Driver Development Kit are granted a limited license to use and/or make copies of these materials for use by others in order to develop graphics peripheral device drivers for Autodesk products. This limited license does not include: 1. Distributing the ADI Kit in connection with any other product. 2. Making the ADI Kit available for any consideration or "disk fee." 3. Distributing the ADI Kit in modified form. Autodesk, Inc. makes no warranty, either expressed or implied, including but not limited to any implied warranties of merchantability or fitness for a particular purpose, regarding these materials and makes such materials available on an "as-is" basis. In no event shall Autodesk, Inc. be liable to anyone for special, collateral, incidental, or consequential damages in connection with or arising out of purchase or use of these materials. The sole and exclusive liability to Autodesk, Inc., regardless of the form of action, shall not exceed the purchase price of the materials described herein. Autodesk, Inc. reserves the right to revise and improve these materials as it sees fit. This publication describes the state of the ADI Kit at the time of its publication, and may not reflect the ADI Kit at all times in the future. The latest version of the ADI Driver Development Kit, including printed documentation, may be obtained by sending $100 in check, VISA, or MasterCard to: ADI Program Autodesk, Inc. 2320 Marinship Way Sausalito, California 94965 Add $6 sales tax if you are located in California. Comments on these materials are welcome. Correspondence may also be exchanged on the Autodesk, Inc. Forum on CompuServe. Type GO ADESK when you log on. IBM and PC-DOS are registered trademarks of International Business Machines Corporation. MS-DOS is a trademark of Microsoft Corporation. Intel is a trademark of Intel Corporation. CompuServe is a registered trademark of CompuServe Incorporated. AutoCAD is a registered trademark of Autodesk, Inc. Autodesk Device Interface/ADI, ADE, 3D Level 1, CAD/camera, AutoLISP, AutoSHADE, AutoSketch, and AutoCAD AEC are trademarks of Autodesk, Inc. Table of Contents Chapter 1 THE AUTODESK DEVICE INTERFACE/ADI ................ 1 1.1 Overview ............................................ 1 1.2 Developer's Responsibilities ........................ 1 1.3 What You Need ....................................... 1 1.4 What The ADI Kit Includes ........................... 1 1.5 Working with ADI .................................... 1 1.6 Testing ............................................. 2 1.7 Releasing the Driver ................................ 2 Chapter 2 THE ADI GRAPHICS DISPLAY SPECIFICATION ........... 3 2.1 The ADI Graphics Display ............................ 3 2.2 Configuration ....................................... 3 2.3 The ADI Graphics Display Interface .................. 4 2.4 Writing Display Drivers ............................. 5 2.5 Display Driver Functions ............................ 6 2.6 AutoCADR Standard Colors ........................... 15 2.7 ADI Graphics Display Test Procedures ............... 16 Chapter 3 THE ADI DIGITIZER SPECIFICATION ................. 21 3.1 The ADI Digitizer .................................. 21 3.2 Configuration ...................................... 21 3.3 The ADI Digitizer Interface ........................ 21 3.4 ADI Digitizer Test Procedures ...................... 25 Chapter 4 THE ADI PLOTTER SPECIFICATION ................... 29 4.1 The ADI Plotter .................................... 29 4.2 Configuration ...................................... 29 4.3 Using the Driver ................................... 31 4.4 Output Format ...................................... 31 4.4.1 File Format .................................. 33 4.5 Installed Driver Operation ......................... 34 4.6 ADI Plotter Test Procedures ........................ 36 Chapter 5 THE ADI PRINTER/PLOTTER SPECIFICATION ........... 37 5.1 The ADI Printer/Plotter ............................ 37 5.2 Configuration ...................................... 37 5.3 Using the Driver ................................... 39 5.4 Output Format ...................................... 39 5.5 Installed Driver Operation ......................... 40 5.6 ADI Printer/Plotter Test Procedures ................ 42 Appendix A REVISION HISTORY ............................... 43 A.1 ADI Display Interface Version 2.0 (October, 1986) .. 43 A.2 ADI Display Interface Version 2.1 (December, 1986) . 43 __________________________________________________________________ Chapter 1 THE AUTODESK DEVICE INTERFACE/ADI __________________________________________________________________ 1.1 Overview The Autodesk Device Interface is an interface specification that allows manufacturers, dealers and users to develop graphics peripheral drivers that work with MS-DOS versions of AutoCADR, AutoSketchtm, and other Autodesk products. By using the ADI, a developer can write, test, distribute and support a peripheral driver that is compatible with Autodesk software products without having to wait for Autodesk, Inc. to implement the driver. 1.2 Developer's Responsibilities ADI drivers are distributed and supported by the developer (you), not by Autodesk, Inc. It is your responsibility to inform users how to install and configure your driver and peripheral. If you are a peripheral manufacturer, and wish to use the ADI Development Kit, you must supply Autodesk with the name of a technical support contact person in your organization. Autodesk's product support staff will be supplied with a list of these names, and questions from users about your driver will be referred to that person in your organization. 1.3 What You Need To implement an ADI driver, you should be familiar with AutoCAD or the Autodesk product you intend to support and its operation. You must purchase the Autodesk product to test your finished interface. An ADI driver may be written in any language that can utilize MS-DOS software interrupts; however, the examples in this documentation are in Lattice C, version 2.14 or 2.151, or in assembly language. 1.4 What The ADI Kit Includes The ADI Kit contains C and assembly language sample source code and this documentation. The sample source code, or any portion thereof, can be used in your ADI driver implementation, without any royalties or additional fees paid to Autodesk, Inc. ____________________ 1The examples in the ADI Development Kit are intended for use with Lattice C version 2.14 or 2.15. If you are using a later version of this compiler, or another compiler, you will need to modify the examples accordingly. 1 The Autodesk Device Interface - Chapter 1 The disk files also include batch files, link files, sample installation guide text, and debugging aids. 1.5 Working with ADI Because of resource limitations, Autodesk cannot provide technical assistance to ADI Kit developers. ADI Kit users are expected to have sufficient technical skills to implement their drivers without assistance from Autodesk. If a bug or deficiency is discovered in the ADI Kit, developers will be notified through the Autodesk Forum on CompuServe. ADI Kit users may wish to exchange information through the Developers' Corner in the Autodesk Forum on CompuServe. Type GO ADESK when you log on to CompuServe. 1.6 Testing The importance of testing your finished ADI driver cannot be overemphasized. This documentation describes the tests that Autodesk's Quality Assurance Department performs AS A MINIMUM for every device driver supported. Since you are responsible for the support of the finished ADI driver, this testing is critical to the success of your driver and also to reduce the volume of user support calls that may be generated and directed to you due to a malfunctioning driver. 1.7 Releasing the Driver How you distribute your ADI driver is up to you. You may want to ship it on a disk included with your product, or make it available to your dealers. The AutoCAD files DSGEN.DRV, DGGEN.DRV, PLGEN.DRV, and PPGEN.DRV may not be distributed by you. These drivers are proprietary Autodesk software products and are specific to individual AutoCAD releases. AutoCAD users may obtain updates of these drivers (if necessary) from their authorized AutoCAD dealer. Versions of these drivers are included in each AutoCAD MS-DOS release (along with the other peripheral device drivers). Your driver should continue to work with new releases of Autodesk software products without any changes required. New features added to the ADI interface may require that you update your ADI driver in order to take advantage of them. Autodesk, Inc. may choose to publish a list of hardware manufacturers and other developers known to have completed ADI device drivers. These lists may be distributed to dealers and posted in the Autodesk Forum on CompuServe. To be eligible for this list, you must send Autodesk, Inc. a copy, on disk, of your completed ADI driver, along with all user documentation. Send it to the ADI Program, Autodesk, Inc., 2320 Marinship Way, Sausalito, CA 94965. 2 ___________________________________________________________________ Chapter 2 THE ADI GRAPHICS DISPLAY SPECIFICATION __________________________________________________________________ The following describes, in detail, the interface specification for ADI graphics display drivers. 2.1 The ADI Graphics Display The ADI Driver Development Kit disk for graphics displays contains source and executable code for an ADI Hercules Graphics Card driver (DSHERC.C). The IWAIT.ASM routine is also on this disk (more on this later). DSHERC.C has numerous debugging features and can emulate a dumb display that clears everything on flip screen, or a smart one with higher level features just by compiling with DUMB or SMART defined. The disk also contains source and executable for the DSDEMO debugging aid, as well as ADI.H (functions common to all ADI drivers), and DSADI.H (functions for graphics display drivers). 2.2 Configuration The driver, DSGEN.DRV, is integrated into selected versions of AutoCADR. This driver appears on the AutoCAD Display options menu as ADI display Vxx.1 DSGEN.DRV performs its functions by calling a DOS "terminate and stay resident" display driver (the one you create) installed before AutoCAD was executed. When AutoCAD is configured with DSGEN.DRV, one of the configuration questions asked is the interrupt vector number used to communicate with your installed driver. ____________________ 1DSGEN.DRV was first distributed in the IBM PC/XT/AT version of AutoCAD 2.18 shipped in March of 1986. This driver appears as ADI display v2.18 on the menu selection. AutoCAD 2.18 users must have this driver for the ADI graphics display to work--DSGEN.DRV with an earlier file date-stamp will not function correctly. This driver is available to users as an update from their dealers. AutoCAD 2.5 (or later version) users must have the DSGEN.DRV distributed with their AutoCAD. See the appendix to this document for a list of which versions of DSGEN.DRV support which features. To use all of the extended functions of the ADI display interface introduced in this version of the kit (version 2.1), users must have AutoCAD 2.52 and the DSGEN.DRV that appears in the AutoCAD configuration menu as ADI display V2.1 (or later). 3 ADI Graphics Display Version 2.1 - Chapter 2 The generic display driver communicates with the installed driver through the registers AX, BX, CX, and DX. Arguments are loaded into these registers and the driver is invoked with an INT to the vector used to call the driver. AX is always loaded with a function code that selects the task the driver is to perform. The other registers have meanings that vary from function to function. The display driver returns its status in the same four registers. The meaning of the results returned depends upon the function. 2.3 The AutoCAD Graphics Display Interface It is necessary to understand what the AutoCAD display interface looks like and how it works. To accomplish this, it is suggested that you experiment with AutoCAD and its features as they relate to the display (virtually all of them do). Conceptually, AutoCAD's display interface uses two screens - a text screen of X rows by Y columns (the "hidden" screen), and a graphics screen of X pixels by Y pixels (see illustration in the Introduction to the AutoCAD Drafting Package Reference Manual). The AutoCAD user may flip between these screens at any time by the push of a function key. The text screen contains the last 25 lines of text. The graphics screen is logically divided into four windows: the graphics area, the text scrolling area, the status line, and the screen menu area. The last three of these areas can be configured on or off at the user's option, in order to maximize the graphics area of the screen. Since not all display hardware has the ability to store and manipulate a complete graphics bitmap AND a full screen of text, AutoCAD will take care of certain functions that the display device cannot handle. The ADI driver must tell AutoCAD what capabilities it has through a series of initialization calls. For example, if the display device and driver are not capable of storing and scrolling an 80 x 25 character text screen, AutoCAD will keep a buffer of 2000 characters and scroll it as needed. There are two forms of display devices: those that can operate in a single screen mode and those that operate in a dual screen mode. Dual screen devices use one monitor for the graphics display and another monitor for the text screen. Examples of currently supported dual screen displays are the Control Systems Artist I and the Number Nine Revolution board. Single screen displays use only one monitor. Examples of single screen displays are the Hercules Graphics Card and the IBM Enhanced Graphics Adapter. A user configuring AutoCAD for use with an ADI driver will configure AutoCAD according to the AutoCAD Drafting Package Installation/Performance Guide for an ADI display and the instructions you provide. You should fully acquaint yourself with this process in order to provide clear documentation for users of your ADI driver. 4 ADI Graphics Display Version 2.1 - Chapter 2 2.4 Writing Display Drivers Thanks to a magical routine called IWAIT, display drivers may easily be written in C. A display driver should be written essentially as a large loop. After doing any once-only initialization, the driver should fall into a loop as follows: while (1) { iwait(VECTOR, &iregs, &oregs); ... processing ... } IREGS and OREGS are structures consisting of four SHORTs corresponding to the registers AX, BX, CX, and DX. For example: struct cregs { short ax, bx, cx, dx; }; static struct cregs iregs, oregs; On the first call to IWAIT, the program will be installed at the interrupt vector given by VECTOR, and will terminate but remain resident. When a user makes an INT to that vector, the contents of his AX through DX will be stored in IREGS and the IWAIT will "return" to the resident program. It may do whatever it likes, then load its results in OREGS, and re-execute the IWAIT. You may notice that IWAIT is a complement of the Computer Innovations C86 library function, SYSINT (except that it uses fewer registers). In fact, a pair of programs doing SYSINTs and IWAITs form a coroutine linkage. IREGS and OREGS may (and usually will) be the same structure. For more information on this linkage (which makes lots of difficult things easier to do), look at the demo program DSDEMO.C, as well as DSHERC.C. The ultimate reference, of course, is the code in IWAIT.ASM. To aid in identifying the ADI driver, the developer should include a message, displayed at driver load time, indicating the version number of the driver, the name of the developer, and the date the driver was created. WARNING !! Both MS-DOS and the Lattice C compiler rely on the decrement flag being CLEAR. If your driver sets the decrement flag (i.e. doesn't perform a CLD instruction before returning to AutoCAD) horrible, horrible things will probably happen. 5 ADI Graphics Display Version 2.1 - Chapter 2 2.5 Display Driver Functions In the following descriptions of the arguments passed to and from the driver, two items enclosed in parentheses means that they are stored as a single 16 bit value, with the first item in the most significant 8 bits and the second item in the least significant 8 bits. INIT1 Code (AX): 1 Arg1 (BX) = (0, config) Arg2 (CX) = (0, intlevel) Result Code (AX): ok Res1 (BX) = ixdots Res2 (CX) = iydots Res3 (DX) = ixdotsm The INIT1 is the initial call to the driver. The CONFIG argument specifies the screen configuration requested by the user when the driver was installed. It is a bit coded value, with the 1 bit indicating that the text scrolling area is desired, the 2 bit indicating that the screen menu is to be drawn, and the 4 bit indicating that the status line is to be used. INTLEVEL identifies the version of the driver interface for upward compatibility. This version of the driver passes 3 for INTLEVEL. The driver returns IXDOTS and IYDOTS equal to one less than the horizontal and vertical size, respectively, of the graphics area of the screen (less menu, scrolling area, and status line). IXDOTSM is the maximum horizontal dot number, including screen menu, beginning at zero (total dots in x direction = IXDOTSM + 1). If the device was correctly initialized, OK should be returned equal to 1, otherwise it should be set to 0. INIT2 Code (AX): 2 Result Res1 (BX) = (modelinl, mnuchars) Res2 (CX) = (maxboxes, modes) Res3 (DX) = (split, hwfill) The INIT2 call causes the driver to furnish additional information to AutoCAD. MODELINL is the number of characters available for the mode status line. MNUCHARS is the number of characters available for screen menu items. MAXBOXES is the number of screen menu boxes on the screen. MODES is a bit coded field that specifies modes pertaining to the operation of this display device. The 1 bit indicates that echoing a Control C to the screen while in graphics mode will destroy the display, and therefore that Control C should be suppressed. This mode should be set only on single screen displays that lack separate image planes for text and graphics. The 2 bit should be set if this display implements highlighting for selected objects (preferably by drawing them with dashed lines). The 4 bit is set if this is a single screen that switches between a text screen and graphics screen, and should be clear if the driver supports a separate graphics screen. If this is a single screen display, SPLIT specifies the number of lines of text that appear in the text 6 ADI Graphics Display Version 2.1 - Chapter 2 scrolling region (normally three). If this is a dual screen display (bit 4 clear in MODES), SPLIT should be set to zero. HWFILL is set to 0 for devices without hardware fill, and 2 for those with polygon fill (1 is not used). INIT3 Code (AX): 3 Result Res1 (BX) = pixwid Res2 (CX) = pixhgt Res3 (DX) = (hidlines, hidcols) The INIT3 call requests further information from the driver. PIXWID is the horizontal physical spacing between pixels, and PIXHGT is the vertical physical spacing between pixels. The ratio of PIXWID and PIXHGT is used to correct the "aspect ratio" of objects drawn on the screen so that horizontal and vertical measurements are equal on the screen. On a device with "square pixels", PIXWID and PIXHGT should both be set to 1. On devices with different X and Y scales, PIXWID and PIXHGT should be set based on the physical screen measurement in each direction divided by the number of pixels on that axis. Only the ratio of PIXWID and PIXHGT is significant, so any desired units may be used. PIXWID and PIXHGT should be made as accurate as possible; changes in the second decimal place in the ratio make visible changes on the screen. PIXWID and PIXHGT must be greater than 0 and less than 32767. The values HIDLINES and HIDCOLS (normally 25 and 80, respectively) give the number of lines and characters to be used for the "hidden" screen. If the driver does not require AutoCAD to maintain a hidden screen, both of these values should be returned as 0. INIT4 Code (AX): 4 Result Res1 (BX) Res2 (CX) The INIT4 function requests further information from the driver. Res1 and Res2 are the upper and lower halves (respectively) of a 32-bit flag field, i.e. [(Res1)(Res2)]. Each bit, when set ON (1), specifies the presence in the driver of a handler for various extended functions. The currently available functions are: Code Function Use EF_SYNC SYNC Flush local display buffers EF_REDRAW REDRAW Redraw from local display buffers (or) clear local display buffers EF_CMD DSCOMAND Register to receive commands EF_XPCMD DSXPCOMD Register to receive transparent commands INIT5 Code (AX): 5 Result Res1 (BX) = ymenumax Res2 (CX) = iydotsm The INIT5 call requests further information from the driver. YMENUMAX specifies the number of pixels assigned to the screen menu area. This normally equals the value returned by the INIT1 7 ADI Graphics Display Version 2.1 - Chapter 2 function for IYDOTS. If the screen menu has a height different from the graphics portion of the screen, YMENUMAX should be set to whatever that height is. IYDOTSM is the maximum vertical dot number of the screen in pixels, including the text scrolling area and the status line (total dots in y direction = IYDOTSM + 1). After the INIT5 call is processed, the screen should be in graphics mode, cleared, any borders between logical screen areas drawn, and ready to accept graphics mode commands. TERM Code (AX): 9 The TERM call indicates that AutoCAD is leaving the drawing editor and that the driver should perform any cleanup desired. A single screen display will always be in text mode when this call is made. CLEAR Code (AX): 10 Result Res1 (BX) = repaint The graphics portion of the screen should be cleared. The menu, scrolling area, and status line should not be disturbed. If this is not possible, set REPAINT as the sum of: 1 to redraw the status line, 2 to redraw the menu, and 4 to redraw the text scrolling area. Otherwise, repaint should be 0. If the driver draws borders on the screen and they are destroyed by clearing the screen, CLEAR should replace them. DOT Code (AX): 11 Arg1 (BX) = x Arg2 (CX) = y The driver should XOR the dot at the location given by X and Y. If a multi-plane color display, the dot should be XORed in all planes. This function is currently used for the GRID command in AutoCAD and may be tested by using that command. MOVE Code (AX): 12 Arg1 (BX) = from_x Arg2 (CX) = from_y Arg3 (DX) = (0,drawmodes) The driver should save from_x, from_y, and drawmodes for use when drawing the next vector or filled polygon. Each MOVE call will be immediately followed by a DRAW or FLOOD call. If the following call is a DRAW, from_x and from_y are the start point of the vector to be drawn. If the following call is a FLOOD, from_x will be the number of vertices in the polygon, and from_y will be -2. For either DRAW or FLOOD, drawmodes is a bit-coded field that specifies certain drawing modes. Currently defined bits are: 8 ADI Graphics Display Version 2.1 - Chapter 2 Name Value Meaning DR_HILITE 1 The vector/area should be highlighted. DR_NORDRW 2 The vector is not part of a drawing entity and should not be displayed on REDRAW calls. The DR_HILITE bit should be saved as the "highlighting status" for the following DRAW or FLOOD call. The DR_NORDRW bit marks vectors that are not part of any drawing entity (for example, the two lines forming a marker blip), but are simply screen artifacts. This is provided for drivers that use the REDRAW entry, and marks vectors that should NOT be redrawn on the next REDRAW request. DRAW Code (AX): 13 Arg1 (BX) = to_x Arg2 (CX) = to_y Arg3 (DX) = color The driver should draw a vector from the saved FROM_X, FROM_Y point to TO_X, TO_Y. If COLOR is positive, that color should be used (see AutoCAD Standard Color Assignments). If COLOR is zero, the vector should be erased (preserving the background color if it is something other than black). If COLOR is -1, the vector should be XORed with the background in all image planes. If the driver implements highlighting, COLOR is positive, and the current highlighting status is 1 (see the MOVE command above), the vector should be drawn highlighted (preferably dashed). Otherwise a solid vector should be drawn. MOVE will always be called immediately before DRAW.2 FLOOD Code (AX): 14 Arg1 (BX) = x Arg2 (CX) = y Arg3 (DX) = color The driver should handle the X, Y information depending on the type of hardware fill it implements. If the HWFILL result from the INIT2 function call was 0, the FLOOD function will never be called. If HWFILL was 2, this function will be called once per vertex of the polygon to be filled, preceded and followed by a special call with Y equal to -2 and X equal to the number of vertices in the polygon. If COLOR is positive, the filled area should be that color (see AutoCAD Standard Color Assignments). If COLOR is zero, the area should be erased (preserving the background color if it is something other than black). If the ____________________ 2It is not unusual for some graphics controllers to draw a different set of pixels depending on the direction the vector is drawn. If garbage is left on the screen after erasing a polyline or solid, you might try sorting the coordinates before drawing the vector. 9 ADI Graphics Display Version 2.1 - Chapter 2 driver implements highlighting, COLOR is positive, and the current highlighting status is 1 (see the MOVE command above), the filled area should be highlighted (usually by highlighting every 5th line of the fill). MOVE will always be called immediately before the first FLOOD call for a given polygon. MARK Code (AX): 15 Arg1 (BX) = cur_x Arg2 (CX) = cur_y Arg3 (DX) = cursel Result Code (AX): can_do The device should draw a cursor of type CURSEL. CURSEL values of 0 and 3 specify simple full screen orthogonal crosshairs, and the display driver may choose to draw these with optimized code. The cursor should be drawn at screen coordinates CUR_X, CUR_Y. If the device does not implement a cursor, or cannot a draw a cursor of a certain type, it should do nothing and return a code of 0. AutoCAD will then draw the cursor itself. If the driver itself draws the cursor, a code of 1 should be returned. The driver should return a code of 0 for all values of CURSEL other than 0 or 3. CMARK Code (AX): 16 Arg1 (BX) = cur_x Arg2 (CX) = cur_y Arg3 (DX) = cursel Result Code (AX): can_do The device should clear a cursor of type CURSEL (see above) at screen coordinates CUR_X, CUR_Y. If the device does not implement a cursor, or cannot clear a cursor of a certain type, it should do nothing and return a code of 0. AutoCAD will then clear the cursor itself. If the driver itself clears the cursor, a code of 1 should be returned. The driver should return a code of 0 for all values of CURSEL other than 0 or 3. CHAR Code (AX): 20 Arg1 (BX) = char The character specified by CHAR should be drawn on the graphics screen at the current text position. (See commands below that set the current text position.) The current text position should be moved one character to the right. ECHAR Code (AX): 21 This function indicates the end of a text string sent by CHAR functions. MHLITE Code (AX): 22 Arg1 (BX) = nchars Result Res1 (BX) = send_chars The driver should highlight the menu box specified by the current text position. NCHARS is the number of characters in the menu 10 ADI Graphics Display Version 2.1 - Chapter 2 box. If the driver can highlight the box without knowing the characters within it, it should return SEND_CHARS equal to 0. Otherwise, it should return SEND_CHARS equal to 1 and AutoCAD will send the contents of the box to the driver with NCHARS calls on the CHAR function, followed by an ECHAR function. MDHLITE Code (AX): 23 Arg1 (BX) = nchars Result Res1 (BX) = send_chars The driver should de-highlight the menu box specified by the current text position. NCHARS is the number of characters in the menu box. If the driver can de-highlight the box without knowing the characters within it, it should return SEND_CHARS equal to 0. Otherwise, it should return SEND_CHARS equal to 1 and AutoCAD will send the contents of the box to the driver with NCHARS calls on the CHAR function, followed by an ECHAR function. MNUCUR Code (AX): 24 Arg1 (BX) = boxno Arg2 (CX) = nboxes The current text cursor should be set to BOXNO on the screen (0 is the top box). There are NBOXES on the screen. This function may be followed by CHAR functions to write into the box, or MHLITE and MDHLITE functions to highlight or de-highlight the box. TPROMPT Code (AX): 30 The current text cursor should be set to the prompt line on the screen. This function will be followed by CHAR functions to write into the prompt line. This function will be used only on dual screen displays (4 bit clear in MODES result of INIT2). QPLOT Code (AX): 31 Result Code (AX): can_do The driver should perform a screen dump to printer. If the driver cannot do this, it should do nothing and return CAN_DO equal to 0. If the driver did do the screen dump, CAN_DO should be returned equal to 1. RPEN Code (AX): 32 Result Res1 (BX) = status Res2 (CX) = pen_x Res3 (DX) = pen_y The driver should sense the position of the screen pointing device (e.g. light pen) and return its current position in PEN_X and PEN_Y in terms of pixels on the graphics screen. STATUS should be set to 2 for a tracking coordinate and 3 for a pick. If the driver supports a "function box" picks from it may be returned with STATUS equal to 4 and PEN_X set to the button number (the first button is number 0). Function box picks will select items 11 ADI Graphics Display Version 2.1 - Chapter 2 from the AUX1 menu. If there is no screen pointing device, or the device is not responding, STATUS should be returned as 0. GOTEXT Code (AX): 33 The driver should switch to the text screen, and clear it. The cursor on the text screen should be left at the top of the screen. Subsequent to this call, AutoCAD will use regular DOS I/O to write to the text screen. This call will occur only on a single screen system (bit 4 set in MODE result from INIT2 function). GOTEXTU Code (AX): 34 The driver should switch to the text screen, displaying hidden screen information. If the driver maintains its own hidden screen, it should switch to the text screen and see that the hidden information appears with the cursor on the text screen left after the hidden information. If the driver asked AutoCAD to maintain the hidden screen (by setting HIDLINES and HIDCOLS in the result to the INIT3 function), it should simply switch to the text screen, clear it, and leave the cursor at the top. AutoCAD will automatically rewrite the hidden screen. Subsequent to this call, AutoCAD will use regular DOS I/O to write to the text screen. This call will occur only on a single screen system (bit 4 set in MODE result from INIT2 function). GOGRAPH Code (AX): 35 Result Res1 (BX) = repaint The driver should switch to the graphics screen. Ideally, this operation should be non destructive, leaving the picture, text scrolling area, status line, and screen menu exactly as they were when the screen was switched to the text screen. If the driver can switch to the graphics screen non-destructively, it should return REPAINT equal to 0. If it cannot, it should return REPAINT as the sum of the following codes that instruct AutoCAD to redraw various information on the screen: 1 to redraw the status line, 2 to redraw the menu, 4 to redraw the text scrolling area, and 8 to redraw the picture in the graphics area. Note that if the 8 bit is set, causing AutoCAD to redraw the picture, the redraw process will call the CLEAR function. If the CLEAR function in turn uses REPAINT to restore the status, menu, or text scrolling area, there is no need to request restoration of these items in the REPAINT result returned by the GOGRAPH function. If the driver has drawn borders or other information on the screen not known to AutoCAD, and this information was destroyed by switching to the text screen and back, it is the responsibility of the driver to redraw it on a GOGRAPH function. This function will only be called on a single screen system (bit 4 set in MODE result from INIT2 function). 12 ADI Graphics Display Version 2.1 - Chapter 2 WRSPLIT Code (AX): 36 Arg1 (BX) = char The driver should write the character CHAR to the graphics screen at the current text position. If the driver implements the hidden screen itself, the character should also be saved on the hidden screen. If the driver is letting AutoCAD maintain the hidden screen (by setting HIDLINES and HIDCOLS in the result of the INIT3 function), the driver need only draw the character on the graphics screen; AutoCAD will take care of saving it. The current text position should be moved one character to the right. MODELINE Code (AX): 37 Arg1 (BX) = length Arg2 (CX) = color The driver should set the current text position to the start of the mode status line. LENGTH specifies the number of characters that will be sent via the CHAR function following this function. An ECHAR function will terminate the string. The current drawing color (color new entities will appear in, however derived) is passed in COLOR so that the device can, if it chooses, represent this on the mode status line. COORDLINE Code (AX): 38 Arg1 (BX) = length The driver should set the current text position to the start of the coordinate status line (usually one more than MODELINL). LENGTH specifies the number of characters that will be sent via the CHAR function following this function. An ECHAR function will terminate the string. SYNC Code (AX): 50 Informs drivers with local display buffers to force those buffers to be drawn, bringing the picture into sync with AutoCAD's internal state. For example, this can be called before digitizer samples are taken to ensure that the entire picture is on the screen for the user to pick from. REDRAW Code (AX): 51 Arg1 (BX) = clear flag Result Code (AX): 0 - Unable to redraw complete picture 1 - Complete picture redrawn Arg1 = 0 - Perform a REDRAW When a redraw of the picture is necessary, AutoCAD will call this entry with an argument of 0 to get it to attempt to do the redrawing of vectors. AutoCAD will still call CLEAR before and will draw grid dots, etc. afterwards. If this returns a ZERO value, AutoCAD will assume that the driver has declined to do the job, and will redraw the image vector by vector as usual. 13 ADI Graphics Display Version 2.1 - Chapter 2 Arg1 = 1 - Flush display buffer When the current contents of any display buffer are no longer valid, AutoCAD will call this entry with argument 1 to indicate that the vector space should be cleared. No return status is necessary. DSCOMAND Code (AX): 52 Arg1 (BX) = string length Arg2 (CX) = string OFFSET Arg3 (DX) = string SEGMENT Result Code (AX): 0 - Command not recognized 1 - Command recognized and processed The driver has (in the INIT4 function) requested that it be allowed to examine all input commands that are not recognized by AutoCAD. The command string location is passed as a SEGMENT/OFFSET pair in DX/CX, with the string length in BX. The command string is terminated by a zero byte in the usual C fashion. If the driver returns 0 in AX, AutoCAD will proceed with its unknown command handling; if the driver returns a 1, AutoCAD will assume that the string has been recognized and processed by the driver, and will behave as if it were any valid AutoCAD command (e.g. a null line will repeat the command). DSXPCOMD Code (AX) 53 Arg1 (BX): command character Result Code (AX) 0 - Command not recognized 1 - Command recognized and processed The driver has (in the INIT4 function) requested that it be notified when a special transparent display driver command character is entered. Currently, there is only one such character - Ctrl-L (0C hexadecimal). The character is supplied in BX. If the driver returns 0 in AX, AutoCAD will proceed with its unknown character handling; if the driver returns a 1, AutoCAD will assume that the character has been recognized and processed by the driver. The transparent control character may be entered AT ANY TIME by the user, and will be immediately passed to the driver. 14 ADI Graphics Display Version 2.1 - Chapter 2 2.6 AutoCAD Standard Colors Whenever a color value is passed from AutoCAD to the ADI Graphics Display driver, the following mapping should be used: 0 Background (erase) 1 red 2 yellow 3 green 4 cyan 5 blue 6 magenta 7 white 8-15 usually intensified version of above (for RGBI type devices) For displays that use 256 colors, the hue resulting from an AutoCAD color 10-249 will be determined by its first two digits, and the saturation and value from the last digit, as follows: Hues: 10 Red 50 Yellow 90 Green 130 Cyan 170 Blue 210 Magenta Between each of these are three intermediate hues, e.g., between red and yellow, we have: 20 reddish orange 30 orange 40 yellowish orange To each hue number, 0, 2, 4, 6, or 8 can be added to give a different "value", or brightness, with 0 the brightest and 8 the weakest. Finally, 1 can be added to produce a "half-saturated", or pastel, color. For example, color 18 is the dimmest red and 10 the brightest red, 19 is the dimmest pink and 11 the brightest pink. Colors 8 and 9 are up for grabs; typically various greys or sometimes black. When AutoCAD asks the driver to draw in a color that matches the background color, then white should be used (unless the background color is white, in which case black should be used). Included on the ADI diskette is the file CHROMA.DWG, an AutoCAD drawing that shows all colors 1-255. You should use this sample drawing for debugging your driver. 15 ADI Graphics Display Version 2.1 - Chapter 2 2.7 ADI Graphics Display Test Procedures Included in the ADI Development Kit is a set of files for testing graphics display drivers. These files use the AutoLISP LISP interpreter built into AutoCAD to automate the testing of graphics display drivers. Type (load"DSTEST") at the AutoCAD COMMAND: prompt, or rename DSTEST.LSP to ACAD.LSP to have the program loaded automatically when AutoCAD is started. Type "single" or "dual" at the AutoCAD prompt to test those configurations. If you wish, you may also wish to perform the manual test procedures outlined below. Manual test procedures follow: 1) Set up the machine to be tested with the display board, an appropriate monitor, and a digitizer. 2) Copy the AutoCAD release into a test directory. Configure AutoCAD for the board, monitor, and digitizer you are using. 3) Start a new drawing and perform the following tests. a) Draw a circle. DRAG the placement of the circle on the screen. Garbage from circles drawn by dragging should not appear. ERASE the circle. For ADE3, the circle should be highlighted. Toggle the screen from graphics to text, and back to graphics, with the flipscreen key. Garbage (or the circle) should NOT appear and the border should not disappear. b) Draw a box around the edges of the graphics area, overlaying the borders. (This is most easily done by starting a line at a corner and then continuing the "to points" at each of the remaining corners.) ERASE the box. The borders of the graphics area should not disappear. c) Configure the display with MENU on and COMMAND PROMPT AREA off. Scroll through the menu with the pointing device from top to bottom and back to the top. The Menu items should not scroll (move). Scroll through the menu from bottom to top and back to the bottom. Again, the menu items should not scroll. d) Configure the display with COMMAND PROMPT AREA on. Enter the drawing editor using a large drawing (e.g. CHROMA). Point to the last item in the menu area with the pointing device. Type in REGEN. Enter CONTROL C while the regen is in progress. After the REGEN is canceled, enter several more commands. The command text area should not scroll into the drawing area. 16 ADI Graphics Display Version 2.1 - Chapter 2 e) For COLOR display drivers, check that the colors are correct. Also, if colors for graphics background, menu text and prompt text are configurable, check that the color assignments really work. f) For COLOR display drivers, turn AXIS on, draw something with any color other than that used for the axis, erase the object you drew and flip screen from graphics to text and back again. The axis should NOT be drawn with the color you drew the object in. Also, the border should NOT disappear. g) Draw a wide polyline. MOVE the polyline. Garbage should not appear or be left behind on the screen. ERASE the polyline. There should be no garbage left on the screen. Perform the same steps with a solid.3 4) The next group of procedures involve configuring the STATUS LINE, COMMAND PROMPT AREA, and MENU AREA in all possible on/off combinations and performing tests with each configuration. Use the drawing DSTEST.DWG in the remainder of the tests. Use the accompanying chart to track your progress. a) Go to the AutoCAD configuration menu and configure the STATUS LINE, COMMAND PROMPT AREA, and MENU AREA according to the appropriate step in the chart. b) Enter the drawing editor using DSTEST.DWG. c) Draw a box around the limits of the display (as in 3b above). Make sure that the edges of the display are accessible. d) With the STATUS LINE configured off, there should be no STATUS LINE at the top of the screen. Conversely, if the STATUS LINE was configured on, it should be there and should contain the correct information on layer, modes and coordinates. e) With the COMMAND PROMPT AREA configured off, there should be no command prompt at the bottom of the screen. If the COMMAND PROMPT AREA was configured on, there should be text lines usable at the bottom of the screen (3 lines for single screen, 1 line for dual screen) for entering commands or data. f) With the MENU AREA configured off, there should not be a MENU AREA on the right hand side of the screen. If configured on, the complete menu area should be accessible. Scroll through the MENU AREA from top to bottom and from ____________________ 3See footnote to DRAW function above. 17 ADI Graphics Display Version 2.1 - Chapter 2 bottom to top. You should be able to access from the top of the menu to the bottom. Make sure that picking an entry works. g) Flip screen from graphics to text and back. None of the lines drawn around the display should disappear. h) Draw a unit circle in the middle of the screen. Zoom extents. The border should not clip the circle at the top of the screen. Erase the circle. The borders at the top and bottom edges of the screen should not be erased. Now zoom out and draw another unit circle to the right of the first one such that the distance between the centers is greater than the diameter. Zoom extents. The border should not clip the circles at the sides of the screen. Erase both circles. This should not erase the borders at the sides of the screen. i) Go to step 4a and repeat the above procedures with the next configuration. 18 ADI Graphics Display Version 2.1 - Chapter 2 ADI GRAPHICS DISPLAY TEST CHART STATUS PROMPT MENU PASS/FAIL LINE AREA AREA ___________________________________________________________ Config 1 OFF OFF OFF ______ Config 2 OFF OFF ON ______ Config 3 OFF ON OFF ______ Config 4 OFF ON ON ______ Config 5 ON OFF OFF ______ Config 6 ON OFF ON ______ Config 7 ON ON OFF ______ Config 8 ON ON ON ______ 19 ADI Graphics Display Version 2.1 - Chapter 2 20 __________________________________________________________________ Chapter 3 THE ADI DIGITIZER SPECIFICATION __________________________________________________________________ The following describes, in detail, the interface specification for ADI digitizer drivers. 3.1 The ADI Digitizer The ADI Driver Development Kit contains the information needed to create an ADI digitizer driver for use with Autodesk software products such as AutoCAD and AutoSketch. A demonstration driver for the Microsoft Mouse, DGDEMO.C, is included. This driver requires IWAIT.ASM, ADI.H (functions common to all ADI drivers), and DGADI.H (functions for ADI digitizer drivers). 3.2 Configuration ADI Digitizer drivers may be used with both AutoCAD and AutoSketch. When the AutoCAD user specifies the ADI Digitizer driver from the AutoCAD Configuration Menu, the only configuration question asked is: Hexadecimal interrupt code (INT 0XXh) <79>: The user should respond with the interrupt location at which the digitizer driver is installed. You need to inform the user in your documentation which interrupt to use. The default on new installations is 79h. AutoCAD may be configured to use a different interrupt vector. AutoSketch assumes the ADI digitizer is installed at interrupt 79 and may not be changed. No other configuration questions are required. The developer may choose to include any desired configuration questions when that driver is installed, or may supply them in AUTOEXEC.BAT, etc. 3.3 The ADI Digitizer Interface The generic driver code simply makes calls to an installed driver and passes its responses back to the program. The driver is not a true MS-DOS device driver (although it may be implemented as one), but rather a program that "terminates and remains resident" after patching a call to itself into an interrupt vector by which the program calls it. 21 ADI Digitizer Version 2.1 - Chapter 3 Information is passed back and forth between the program and the driver through the registers AX, BX, CX, and DX. The driver code must preserve all segment registers and the registers SI and DI. Commands to driver Code (AX) Initialize 1 BX = Interface version (1) Terminate 2 Probe 3 When the drawing editor is initialized, the driver will be called with AX equal to 1 (initialize). BX contains a code indicating the revision number of the driver interface (to allow upward compatibility). The current version of the driver passes 1 in BX. The installed driver should perform whatever initialization it wishes and return with a status in AX. If the initialization failed, the driver should return 0 in AX, otherwise 1 if everything went well. If 1 is returned in AX, indicating successful initialization, BX is expected to contain a code indicating the type of the pointing device. If BX is 0, the device is configured as a relative pointing device such as a mouse; tablet menus and tablet mode will be disabled. If BX is 1, the device is configured as a tablet and all tablet-related commands will be turned on. In addition, CX is expected to contain a code indicating whether the pointer sends continuous samples or pauses between samples. If the pointer always responds with a sample, or if pauses are meaningful (for example, they indicate the cursor has been removed from the tablet surface), CX should be set to 0. If the device occasionally returns no sample because of its inherent properties (for example, a device which only reports changes in coordinates), CX should be set to 1. Setting CX incorrectly can cause the crosshairs to blink. If the driver returns zero, the message: Could not initialize pointer driver. will be issued and the device disabled. Before calling the driver to initialize it, the program driver tests whether the configured interrupt vector is nonzero. If it is zero, indicating no driver is installed, and hence that trying to call it would crash the machine, the message: ** No driver is installed for interrupt vector 0XX ** will be issued and the driver disabled. As the drawing editor runs, whenever the program asks for input from the digitizer, the installed driver will be called with 3 in AX (Probe). The driver should respond with one of the following status codes in AX, with additional arguments as indicated. 22 ADI Digitizer Version 2.1 - Chapter 3 Response AX BX CX DX Nothing 0 Tracking point 2 X-coord Y-coord Picked point 3 X-coord Y-coord Button pick 4 Button # Button + coords 5 Button # X-coord Y-coord AX = 0 indicates the pointer had nothing to report. No action is taken by the program. This code may be returned when waiting for a button to be released following a selection. (Note that the program driver does not perform this function--it is the responsibility of the installed driver, as is any debouncing of buttons which may be required). AX = 2 indicates a "tracking" coordinate pair is returned in BX and CX. The X coordinate, in the range from 0 to 20480 inclusive is returned in BX, and the Y coordinate in the same range in CX. This is how coordinates are returned when the pick button is not pressed. The program will track with the screen or menu cursor. AX = 3 indicates a picked coordinate pair is returned in BX and CX. The X coordinate, in the range from 0 to 20480 inclusive is returned in BX, and the Y coordinate in the same range in CX. This code is used to return the coordinates when the "pick" button is pressed. AX = 4 indicates a button has been pressed, which generates a button menu pick. The button number is returned in BX, with the first button indicated by 0, the second by 1, and so on. AX = 5 indicates a button has been pressed, which generates a button menu pick, and that the driver can return the coordinates of the pointer at the time of the button pick. The button number is returned in BX, the X coordinate (0 to 20480) in CX, and the Y coordinate in DX. Devices which return the current pointer position with button menu picks should call function 5 and return the coordinates. Devices which lack this capability should use function 4 described above. If any value other than those given above is returned in AX, the message: ** Pointer driver returned illegal code X. Pointer disabled ** will be issued and the pointer disabled. When the drawing editor returns to the main menu, the installed driver will be called with 2 in AX. This instructs the driver to terminate. 23 ADI Digitizer Version 2.1 - Chapter 3 Note: The point coordinates returned by the digitizer driver should lie in the range 0 to 20480 with (0,0) at the lower left corner of the tablet and (20480,20480) at the upper right. Even relative pointing devices, such as mice, must return absolute coordinates in the range 0 to 20480. If a digitizer tablet has differing height and width, the full range of the SMALLER dimension should be scaled to 0 to 20480, with the larger dimension's coordinates using the same scale. This scheme will result in the larger dimension's coordinates exceeding 20480, though they must remain less than 32768. If Tablet Mode is to function properly, vertical and horizontal digitizer coordinates must represent equal physical distances. 24 ADI Digitizer Version 2.1 - Chapter 3 3.4 ADI Digitizer Test Procedures These test procedures are for use with AutoCAD. If you intend to use your ADI digitizer driver with AutoSketch, we suggest that create a simple drawing with AutoSketch and edit it using all the options in the Change menu. Be sure that you are able to access the entire drawing area and that picking works correctly. 1) Set-up machine for the digitizer you are testing. Cable the digitizer as documented in the AutoCAD Drafting Package Installation/Performance Guide. 2) Configure AutoCAD for the digitizer. 3) Start a new drawing. Cross hairs should appear on screen immediately after bringing up a the drawing. Check that the pointing device moves cross-hairs smoothly across the screen and that the cross-hairs can be moved over the entire drawing screen. Moving the pointing device from the bottom of the digitizer pointing area to the top should move the cross-hairs from the bottom to the top of the screen. Moving the pointing device from the extreme left of the digitizer pointing area to the right should move the cross-hairs from the left of the screen to the right (into the menu area if the menu area is configured on). 4) Check that the "button" options for each supported puck, mouse or stylus work as documented in the Installation Guide. The following table gives the function representation of the Menu item buttons in the standard AutoCAD menu: Menu item button Function ------------------------------------------------------------ 1 = ; (Semicolon) <Return> 2 = Ctrl C;Redraw Redraw drawing in screen area 3 = Ctrl C *Cancel* 4 = Ctrl B Snap mode on/off 5 = Ctrl O Ortho mode on/off 6 = Ctrl G Grid on/off 7 = Ctrl D Coordinate Display 8 = Ctrl E Isometric Plane 9 = Ctrl T Tablet mode on/off 10-16 Not set Note: On the 12 and 16-button cursors, the "*" button can be used to select menu items, but only if the tablet's Cursor Function Disable sequence "**0" has been executed. See page 4- 6 of the Calcomp 9000 Series Digitizer Operator's Manual 50090- 1. 25 ADI Digitizer Version 2.1 - Chapter 3 Note: The black button on the back of the Kraft Joystick or the right button on the pad may be used to select slow motion mode, or to invoke the first item from the button menu. The following procedure steps 5 and 6 test commands with modes that operate outside the "normal" operating environment of AutoCAD commands and are specific to the digitizer and therefore singled out for testing. For definitions of these commands, consult your AutoCAD Drafting Package Reference Manual. 5) Test the pointing device in SKETCH mode. The normal "button" menu cannot be used while a SKETCH command is in progress. 26 ADI Digitizer Version 2.1 - Chapter 3 The following is a list of SKETCH subcommands, and the pointer buttons which correspond to them: Command Character Pointer Buttons Function -------------------------------------------------------------- P "Pick" Raise/Lower pen . (period) 1 Line to point R 2 Record lines X,Space,<Return> 3 Record lines and exit Q,Ctrl C 4 Discard lines and exit E 5 Erase C 6 Connect 6) If testing a Digitizer Tablet: a) Configure the tablet for four Menu areas (Maximum supported) with the standard TABLET TEST SHEET and check to see that all menus are accessible with pointing device by calling up the digitizer test menu "DGTEST". a) Calibrate tablet to area with known dimensions and check various points (Tablet mode on) for accuracy. When calibrating the Tablet, choose two points that require the command to perform coordinate calculations more difficult than those required by picking the origin and another point on either the X or Y axis. 27 ADI Digitizer Version 2.1 - Chapter 3 28 __________________________________________________________________ Chapter 4 THE ADI PLOTTER SPECIFICATION __________________________________________________________________ The following describes, in detail, the interface specification for ADI Plotter drivers. 4.1 The ADI Plotter Kit The ADI Development Kit allows users to interface AutoCAD to plotters and other vector-oriented devices that Autodesk does not directly support. The driver is fully configurable and offers a variety of different output formats. The output from the AutoCAD ADI driver may be sent to an ASCII file, a binary file, or configured to communicate with an installed INT driver. 4.2 Configuration Because the driver is indeed generic, the process of configuring it is more complex than that required by most other plotters. All the hardware information provided by a conventional driver must be supplied by the user when configuring this driver. As a result, the dialogue is extended. First, the driver's output format is selected. The following prompt is issued: Select output format: 0. ASCII file 1. Binary file 2. AutoCAD DXB file 3. Installed INT driver Output format, 0 to 3 <0>: The ASCII and binary file formats will be described later. The DXB file format is described in the AutoCAD Drafting Package Reference Manual. The generic driver can also send commands to a resident driver via an INT call. If this option is selected via option 3, the additional question: Hexadecimal interrupt code (INT 0XXh) <78>: will be issued. The response selects the interrupt vector to be used to communicate with the plotter driver. The default is 78h. Any vector from 1 to 0FFh is permissible. If an invalid reply is entered, the message: 29 ADI Plotter Version 2.1 - Chapter 4 ** Interrupt number must be between 1 and 0FF is given and the prompt reissued. Following the output format dialog, the user is asked whether the plotter is multi-pen: Does the plotter have multiple pens? <N> If this is answered yes, the user is asked: How many pens does it have, 2 to 127 <2>: Next, information on plotter-implemented line styles is requested with the questions: Does the plotter have multiple dashed line styles? <N>, and, How many line styles are there, 2 to 127 <5>: If the plotter provides multiple pen speeds, the user may define them with the questions: Is the plotter variable speed? <N>, and, What is the numeric code for the fastest speed, 1 to 127 <10> These questions supply information which is normally provided by the hardware definition of a plotter within a driver. It is used to enable features in the plot setup process and to provide rudimentary range checking of user specifications. Next the maximum plot size and plotter step size are specified. These arguments may be specified either in inches or millimeters. The units are selected by the prompt: Next you will specify the maximum plot size the plotter can make, and the step size of the plotter. You may specify these either in millimeters or inches. The next question selects the units. Specify plot size in millimeters? <N> If the answer is the default, "no," the prompts that follow and their responses will refer to inches, otherwise millimeters. The examples given below assume inches were selected. 30 ADI Plotter Version 2.1 - Chapter 4 Maximum horizontal (X) plot size in inches? <11.0> Plotter steps per inch in the horizontal (X) direction: <1000.0> Maximum vertical (Y) plot size in inches? <8.5> Plotter steps per inch in the vertical (Y) direction: <1000.0> These parameters are floating point numbers that are used to compute the plotter size in plotter steps. The calculated step count may not exceed 65535. If the specifications given exceed the limit, the following message will appear (after the steps per inch are specified): ** Error: Plot size multiplied by steps per inch cannot exceed 65535. Specifications resulted in ?????. The question marks in the prompt are replaced by the step count the user tried to configure. After this error message, the pair of prompts for plot size and steps per unit are reissued. Once the driver-specific configuration is completed, the regular plotter configuration is performed. The generic plotter driver remembers all its configuration options and supplies them as defaults on subsequent configurations. The defaults given in the prompts above are those assumed on a new configuration of the driver. 4.3 Using the Driver If ASCII, binary, or DXB output format has been selected, the program will prompt for a file name following all the runtime plot configuration dialogue: Enter file name for plot: The user should reply with a file name for the plot data. The name may be entered with a file type, if desired. If none is specified, ".plt" (or ".dxb" in the case of output format option 2) will be used. If the file cannot be opened, the message: Cannot open this file. Try another name? <N> will appear. If answered affirmatively, the file name prompt will reappear; otherwise the plot will be canceled. 4.4 Output Format Regardless of the output format and method, plot data is expressed in a single representation. Each plot command consists of a type code, possibly followed by arguments. The following table gives the plot codes and their arguments: 31 ADI Plotter Version 2.1 - Chapter 4 Function Code Type Argument 1 Argument 2 Begin plot 1 B File level End plot 2 A Move 3 C X coordinate Y coordinate Draw 4 C X coordinate Y coordinate New pen 5 B Pen number Select speed 6 B Speed code Set line type 7 B Line type Pen change 8 A Abort plot 9 A The "type" field in the above table specifies how the information is represented in the file or passed to the driver. Before discussing the representation, let us examine the various plot commands and the meaning of their arguments. The first code generated for any plot is the BEGIN PLOT code. Its argument is a number which specifies the version of the plot command file which follows. Plots generated by this version of the driver will have a file level of 1. The PEN CHANGE code is generated before every pen change at the start of a pass over the vectors. It allows the plotter to prepare for a possible manual pen change (for example, raising the pen and moving it to the middle of the carriage). It is not the actual change pen command, which is the NEW PEN code. Note that a PEN CHANGE command will always be generated at the start of a plot. The NEW PEN code is the actual command that selects a pen. This code is followed by an argument which specifies the pen number. See the Plotting chapter of the AutoCAD Drafting Package Reference Manual for information on how AutoCAD handles the assignment of plotter pens to drawing colors. The SELECT SPEED code chooses a drawing speed for a variable speed plotter. The code is followed by an argument that selects the speed. Note that the speed argument is range checked and will not exceed the maximum speed configured, but is not otherwise checked. For a plotter with discrete speeds, a driver processing this command which encounters a speed number the plotter cannot handle should send the next SLOWER speed. The SET LINE TYPE code selects a plotter line font. This code is followed by an argument which selects the line font. It is a universal convention within AutoCAD that zero selects a continuous (solid line). The meaning of the other fonts is up to the driver. The MOVE code is followed by two arguments, specifying the absolute coordinates to which the pen should be moved with the pen 32 ADI Plotter Version 2.1 - Chapter 4 up. The coordinates are specified X first, Y second, both as unsigned numbers in the inclusive range from 0 to 65535. The DRAW code is followed by two arguments, specifying the absolute coordinates to which the pen should be moved with the pen down. The coordinates are specified X first, Y second, both as unsigned numbers in the inclusive range from 0 to 65535. The END PLOT code is output at the end of a plot. It has no arguments. The ABORT PLOT is relevant only for installed drivers. It is sent to indicate that the plot has been terminated by the user by pressing the interrupt key. If the plot is being sent to a file, this action causes the file not to be generated, so the ABORT PLOT code will never be seen by a program processing a plot file. An installed driver will receive the code to indicate that abnormal termination action should be taken (flushing a buffer, for example). This code will be followed by an END PLOT code, which should perform the usual end of plot functions (such as putting the pen back). 4.4.1 File Format If the output format is an ASCII file, each plot command will appear on a new line, starting in the first text column. All codes and arguments appear as decimal numbers, separated by commas. Type A codes appear by themselves. Type B codes consist of the command code followed by the argument. Type C codes consist of the command code, followed by the X coordinate and Y coordinate, comma delimited. All numbers appearing in a plot file are unsigned. Arguments to type B codes are in the range from 0 to 127, and arguments to type C codes range from 0 to 65535. The following is an actual plot file generated by plotting a square. The annotations did not appear in the original file, but were added to explain the commands. 1,1 Begin plot, file level 1 8 Pen change (start of pass) 5,1 Select new pen 1 7,0 Select line type 0 (solid) 6,1 Select speed 1 3,0,6953 Move to 0, 6953 - pen up 4,6954,6953 Draw to 6954, 6953 - top of square 4,6954,0 Draw to 6954, 0 - right side 4,0,0 Draw to 0,0 - bottom 4,0,6953 Draw to 0, 6953 - left side 2 End of plot In a binary file, the codes and arguments appear precisely as they do in an ASCII file, but are stored as binary numbers. Type A codes are written as single bytes. Type B codes consist of a 33 ADI Plotter Version 2.1 - Chapter 4 single byte code, followed by a one byte argument. Type C codes are written as a single byte code, followed by two 16 bit arguments representing the X and Y coordinates. Each 16 bit argument is written least significant byte first, most significant byte last, the standard 8086 representation. The following is a hexadecimal dump of a binary file generated by the same drawing which created the ASCII file above. Spacing has been added to the dump to aid readability. 01 01 08 05 01 07 00 06 01 03 00 00 29 1B 04 2A 1B 29 1B 04 2A 1B 00 00 04 00 00 00 00 04 00 00 29 1B 02 4.5 Installed Driver Operation The generic plotter driver can communicate with an installed driver. This allows the development of a driver which, once loaded in memory, acts exactly like a driver implemented within AutoCAD itself: plots are performed in real time, without the need for an intermediate file. Installed drivers are implemented as MS-DOS programs that "terminate and remain resident"; they are not true DOS device drivers (although an alternate approach is to use a DOS device driver and send the file output to it). The installed driver should patch itself into a vacant interrupt location then exit to DOS, remaining resident in memory. Installation of the driver must be accomplished before AutoCAD is executed. When the generic driver is configured, the installed driver is selected by the "3" reply to the output format query. The interrupt vector at which the driver installed itself must be specified at configuration time. When a plot is made, the generic plotter driver will first make a rudimentary check to see if the driver is installed: it will test the interrupt vector and only proceed if it is nonzero. If the interrupt vector is zero, the message: ** No driver is installed for interrupt vector 0XX ** will be issued, specifying the interrupt vector in hexadecimal, and the plot will be canceled. 34 ADI Plotter Version 2.1 - Chapter 4 If the driver is properly installed, each plot command will be sent to it by loading the command code and arguments into registers and then calling the driver with an INT instruction to the configured vector. The command code is always passed in AX. For type B commands, the first argument is passed in BX. For type C commands, the X coordinate is passed in BX and the Y coordinate in CX. The driver should return with AX zero. (This is not currently checked, but may be used in the future for a driver status). The driver must preserve the contents of all segment registers, and the registers SI and DI. 35 ADI Plotter Version 2.1 - Chapter 4 4.6 ADI Plotter Test Procedures 1) Configure AutoCAD for the plotter to be tested. Cable the plotter as documented in the AutoCAD Drafting Package Installation/Performance Guide. 2) Use the PLTST2.DWG to test: a) Scaling -Plot the view named "SCALE" to a specified scale (e.g. 1=1). Measure the dimensioned parts of the drawing checking that they are plotted to the scale specified. b) 90 Degree Rotation - Plot the drawing specifying 90 degree rotation, MAX size paper, FIT. The plot should be rotated 90 degrees. The plot should not be truncated; if it is, the paper size is incorrect. c) Linetypes, Pen changes, and Pen speeds - Change the layers in the drawing to use the linetypes supported on the plotter (as documented in the Installation Guide). Also, change the layers to different pen numbers and pen speeds supported on the plotter. Plot the drawing. Check that the different line types were plotted. Check that the correct pens were used. If the plotter only supports one pen, time should have been allowed between plot layers to change the pen. If multiple pen speeds are allowed, the different pen speeds should have been used during the plot. d) Origin Offset - Plot the drawing, specifying an offset from the origin. The plot should move the specified number of units from the origin. e) MAX Size - Plot EXTENTS, MAX size, FIT, no rotation. The drawing should not be truncated. 36 ___________________________________________________________________ Chapter 5 THE ADI PRINTER/PLOTTER SPECIFICATION __________________________________________________________________ The following describes, in detail, the interface specification for ADI Printer/Plotter drivers. 5.1 The ADI Printer/Plotter The ADI Development Kit allows manufacturers and users to interface AutoCAD to printers that Autodesk does not directly support. The sample included in the ADI Kit demonstrates a printer/plotter that simply uses asterisks and spaces for output. 5.2 Configuration Printer/plotters come in a variety of resolutions and sizes, and some support color output. AutoCAD must know these parameters before it can begin a plot. These parameters are set during configuration of the ADI printer/plotter. First the maximum paper size and resolution are specified. These arguments may be specified either in inches or millimeters. The units are selected by the prompt: Next you will specify the maximum plot size the printer can make, and its resolution (dots per unit). You may specify these either in millimeters or inches. The next question selects the units. Specify plot size in millimeters? <N> If the answer is the default, "no," the prompts which follow and their responses will refer to inches, otherwise millimeters. The examples given below assume inches were selected. Maximum horizontal (X) plot size in inches? <11.0> Printer dots per inch in the horizontal (X) direction: <100.0> Maximum vertical (Y) plot size in inches? <8.5> Plotter dots per inch in the vertical (Y) direction: <100.0> These parameters are floating point numbers which are used to compute the printer X and Y size in dots. The calculated sizes may not exceed 65535. If the specifications given exceed the limit, the following message will appear (after the dots per unit are specified): 37 ADI Printer/Plotter Version 2.1 - Chapter 5 ** Error: Plot size multiplied by dots per inch cannot exceed 65535. Specifications resulted in ?????. The question marks in the prompt are replaced by the size the user tried to configure. After this error message, the pair of prompts for plot size and dots per unit are reissued. Finally, the driver's output format is selected. The following prompt is issued: Select output format: 0. Binary file 1. CAD/camera image file 2. Installed INT driver Output format, 0 to 2 <0>: The binary file format will be described later. The CAD/camera image file format is described in the AutoCAD Drafting Package Installation/Performance Guide under ADI Printer/Plotter. The generic driver can also send commands to a resident driver via an INT call. If this option is selected via option 2, the additional question: Hexadecimal interrupt code (INT 0XXh) <7B>: will be issued. The response selects the interrupt vector to be used to communicate with the printer/plotter driver. The default is 7Bh. Any vector from 1 to 0FFh is permissible. If an invalid reply is entered, the message: ** Interrupt number must be between 1 and 0FF is given and the prompt reissued. If binary file format is selected, the user must specify whether color information is to be written to the file (an installed driver provides this information to AutoCAD at initialization time, so this question does not appear if an installed driver is selected). The prompt is: Does the printer/plotter support color? <N> If answered with the default of "No", the output file will be one bit per pixel. If color is selected, the output will be four bits per pixel, and will contain color information. See the AutoCAD Drafting Package Installation/Performance Guide for examples of how various printers handle color information. Once the driver-specific configuration is completed, the regular printer/plotter configuration is performed. The generic 38 ADI Printer/Plotter Version 2.1 - Chapter 5 printer/plotter driver remembers all its configuration options and supplies them as defaults on subsequent configurations. The defaults given in the prompts above are those assumed on a new configuration of the driver. 5.3 Using the Driver If binary file output format has been selected, when a plot is made with the driver, following all the runtime printer plot configuration dialogue, the prompt: Enter file name for plot: will appear. The user should reply with the file in which the printer plot data should be written. The name may be entered with a file type, if desired. If none is specified, ".PRP" will be used (or "IMG" for CAD/camera image file output). If the file cannot be opened, the message: Cannot open this file. Try another name? <N> will appear. If answered affirmatively, the file name prompt will reappear; otherwise the plot will be canceled. 5.4 Output Format Regardless of whether the output is being written to a binary file or passed directly to an installed driver, printer plot data is represented in a uniform fashion. Each record in the file or message to the installed driver begins with a single 16 bit value. If the sign bit is set in this value, it is a control function, otherwise it is a count specifying the number of bytes of plot data that follow. The function codes are given below. Function Code Arguments Begin plot 8001h File_level, Xdots, Ydots, Color End plot 8002h Abort plot 8003h A binary file will begin with the BEGIN PLOT code (all 16 bit values in the file are written in standard 8086 fashion: least significant byte first, most significant byte last), followed by the 16 bit values FILE LEVEL, XDOTS, YDOTS, and COLOR. FILE LEVEL identifies the format of the file for upward compatibility with future extensions. Files written by this version of the driver will have a file level of 1. XDOTS and YDOTS specify the horizontal and vertical size, respectively, of the printer for which this file was generated. COLOR will be 0 if the file is monochrome format (one bit per pixel) and 1 if the file is color format (4 bits per pixel). 39 ADI Printer/Plotter Version 2.1 - Chapter 5 Following the BEGIN PLOT record are zero or more line records. Each line record consists of a 16 bit byte count followed by that number of bytes of raster data. If the printer/plotter was configured as supporting color, each byte will contain two pixels, with 4 bits per pixel indicating color. If the printer/plotter was configured as monochrome, 8 one bit pixels will be stored per byte. In either case, pixels are arranged on the page left to right starting with the most significant pixel of each byte, proceeding to the least significant, then continuing to the next byte. Records in the file are variable length; trailing zero bytes are not written. A totally blank line on the printer will be written with a byte count of 0 and no following data bytes. Totally blank lines at the end of the plot are not written to the file. Consequently there may be fewer line records in the file than the YDOTS count given in the BEGIN PLOT record. The end of the plot is indicated by an END PLOT record instead of a byte count word. The ABORT PLOT item will never be encountered in a printer plot file because aborting the plot causes the output file to be deleted. It is passed to an installed driver to apprise it of the abnormal termination of the printer plot. 5.5 Installed Driver Operation The generic printer/plotter driver can communicate with an installed driver. This allows the development of a driver which, once loaded in memory, acts exactly like a driver implemented within AutoCAD itself: printer plots are performed in real time, without the need for an intermediate file. Installed drivers are implemented as MS-DOS programs that "terminate and remain resident"; they are not true DOS device drivers. The installed driver should patch itself into a vacant interrupt location then exit to DOS, remaining resident in memory. Installation of the driver must be accomplished before AutoCAD is executed. The standard interrupt vector for printer/plotter drivers is 07B hexadecimal. When the generic driver is configured, the installed driver is selected by the "2" reply to the output format query. The interrupt vector at which the driver installed itself must be specified at configuration time. When a printer plot is made, the generic printer/plotter driver first makes a rudimentary check to see if the driver is installed: it will test the interrupt vector and only proceed if it is nonzero. If the interrupt vector is zero, the message: ** No printer driver is installed at interrupt vector 0XX ** will be issued, specifying the interrupt vector in hexadecimal, and the plot will be canceled. 40 ADI Printer/Plotter Version 2.1 - Chapter 5 Commands are passed to the installed driver through the registers. The function code or length in bytes of the data is passed in register AX. The driver should examine AX and react accordingly. The BEGIN PLOT code is passed with the FILE LEVEL in BX. The configured size of the printer/plotter in dots is passed with the horizontal size in CX and the vertical size in DX. The driver must return with AX containing a status code: 1 if the printer was successfully initialized and 0 otherwise. BX should contain a code which selects monochrome or color output format, 0 for monochrome (1bit per pixel), 1 for color (4 bits per pixel). Successive lines of plot data are passed with the length in bytes of each line in AX. BX contains the offset address of the line of data,and CX contains the segment address of the printer data (thus, the full 32 bit address of the line is in CX:BX). DX contains the vertical position of the line on the page (since blank lines within the plot are output, most driver will not need this value and may ignore it). If the line is blank (AX is zero), CX and BX are meaningless. The end of the plot is signaled by the END PLOT code in AX. The driver should eject the page and close out the printer plot. If the printer plot is aborted by the user, the driver will receive the ABORT PLOT code in AX. If possible, the driver should discard information buffered for the printer. The driver will receive an ENDPLOT code after the ABORT PLOT code. A sample driver, intended to illustrate how an installed driver operates, and to exercise the facility for testing, is provided on the disk as PPDRV.C and PPDRV.EXE. This driver sends its data to the printer in "ultimate dumb printer/plotter mode": zero bits are printed as spaces and one bits as asterisks. To configure a 132 column printer for use with this driver, answer the configuration questions: No <use inches> 13.2 <paper width> 10 <characters per inch horizontal> 10 <usable paper height> 6 <characters per inch vertical> This driver supports only monochrome format (one bit per pixel). The driver will read a binary output file and send it to the printer when called with the command: 41 ADI Printer/Plotter Version 2.1 - Chapter 5 PPDRV <file> The extension of .PRP is supplied automatically. The driver may be installed into interrupt vector 07Bh by calling with the command: PPDRV -I Once installed, printer/plotter output may be sent directly to it by using the installed driver output option. 5.6 ADI Printer/Plotter Test Procedures Use the test procedures outlined under ADI Plotter Test Procedures to test your completed ADI Printer/Plotter driver. 42 __________________________________________________________________ Appendix A REVISION HISTORY __________________________________________________________________ This appendix describes changes made in the ADI specification from previous versions. A.1 ADI Display Interface Version 2.0 (October, 1986) These additions are supported in ADI display Vers. 2.0, available in AutoCAD Version 2.52, November, 1986. o Added INIT4 Extended Functions ED_SYNC and EF_REDRAW. o FLOOD function fixed to include color specification. o MOVE calls added prior to FLOOD calls to pass highlight flag. o DSCOMAND and DSXPCOMD added to enable passing of transparent commands to the display driver. o AutoCAD ADI display driver corrected to handle selection of interrupt vectors other than the default, 7Ah. A.2 ADI Display Interface Version 2.1 (December, 1986) These additions are supported in ADI display Vers. 2.1, available as a driver update to AutoCAD Version 2.52, December, 1986. o MOVE fixed to recognize vectors that are not part of a drawing entity (e.g. blips) and which should not be redrawn on REDRAW calls. o MODLINE call fixed to pass correct current entity drawing color. o Fixed machine hang when ADI driver was not found at specified interrupt, or when ADI driver returned 0 (failure) on INIT1 call. 43 --END OF ADIKIT.DOC--